\chapter{使用指南}
\label{ch:usage-guide}

本章介绍日常使用中最常见的命令、配置文件与调优技巧。

\section{命令总览}

\begin{longtable}{ll}
\toprule
\textbf{命令} & \textbf{用途} \\
\midrule
\texttt{convert} & 将 csproj 或单个 cs 文件转换为 C++ \\
\texttt{report} & 输出转换统计信息与成功率 \\
\texttt{doctor} & 检查运行环境是否完整 \\
\texttt{clean} & 删除缓存、桩代码与生成文件 \\
\texttt{config init} & 在项目根目录生成默认配置 \\
\bottomrule
\end{longtable}

\section{配置文件结构}

执行 `cpp-orchestrator config init` 会创建 \texttt{.cpp-orchestrator.yml}：

\begin{lstlisting}[style=yaml]
project: MyGame.csproj
output:
  include: generated-cpp/include
  source: generated-cpp/src
mapping:
  namespace_root: my_game
  user_overrides:
    MyCompany.Utils.Vector3:
      cpp_type: glm::vec3
      includes:
        - glm/glm.hpp
stubs:
  enable: true
  common_header: generated-cpp/include/common_stubs.hpp
report:
  format: markdown
  save_to: reports/latest.md
\end{lstlisting}

关键配置项说明：

\begin{itemize}[leftmargin=*]
    \item \textbf{output}：独立指定头文件与源码目录
    \item \textbf{mapping.namespace\_root}：自定义 C++ 顶级命名空间
    \item \textbf{mapping.user\_overrides}：为特定类型设置自定义映射
    \item \textbf{stubs.enable}：是否生成缺失依赖桩代码
    \item \textbf{report}：控制报告格式（markdown/html/json）
\end{itemize}

\section{类型映射与命名}

\subsection{自定义类型}

\begin{lstlisting}[language=Python]
from orchestrator.mapping.type_mapper import TypeMapper

mapper = TypeMapper()
mapper.add_custom_mapping(
    csharp_type="Color",
    cpp_type="sf::Color",
    includes=["SFML/Graphics/Color.hpp"],
)
\end{lstlisting}

\subsection{命名规则}

命名转换遵循如下策略：

\begin{itemize}[leftmargin=*]
    \item 类、结构体保持 PascalCase
    \item 方法、字段、参数转换为 snake\_case
    \item 常量保持全大写并使用下划线
    \item 常见缩写（ID、HTTP、API、UUID 等）保持连写
\end{itemize}

如需自定义，可在配置文件中加入：

\begin{lstlisting}[style=yaml]
naming:
  preserve_acronyms:
    - SKU
    - GPU
  private_prefix: m_
\end{lstlisting}

\section{桩代码生成}

当 IR 中引用外部类型而项目中缺失时，转换器会自动生成桩代码：

\begin{itemize}[leftmargin=*]
    \item \texttt{common\_stubs.hpp}: 常用数据结构（Person、User、Clan 等）
    \item \texttt{*\_stubs.hpp}: 针对单个类生成的占位类型
\end{itemize}

桩代码旨在让编译通过，开发者可以逐步替换为真实实现。

\section{报告与统计}

执行 `cpp-orchestrator report` 会输出包含以下信息的摘要：

\begin{itemize}[leftmargin=*]
    \item 处理文件数量、成功率
    \item 生成桩代码列表
    \item 类型映射覆盖率
    \item 待人工介入的 TODO 列表
\end{itemize}

\section{最佳实践摘要}

\begin{itemize}[leftmargin=*]
    \item 完整转换流程：Roslyn $\rightarrow$ IR $\rightarrow$ C++ $\rightarrow$ 编译
    \item 自定义类型映射：覆盖 25+ 常见类型
    \item 命名规范：充分利用 snake\_case 与缩写保护
    \item 使用 CMake 构建，统一开启 \texttt{-Wall -Wextra}
    \item 结合报告及时跟踪桩代码与 TODO
\end{itemize}

本章介绍的配置与命令足以覆盖大多数场景，更多案例请参考第 \ref{ch:examples} 章。
